Skip to main content

Create a Contextual Audience

IQM’s REST API enables you to interact with most of our platform's applications.

The following endpoints will be used to create a Contextual Audience:

POST /api/v3/ua/login
POST /api/v3/audience/contextual/add
GET /api/v3/audience/contextual/{audienceId}

About IQM Contextual Audiences​

IQM's Contextual Audience allows you to make groupings of users based on their online activity. By specifying keywords and/or URLs, IQM will build an Audience as users visit sites relevant to those parameters within a target timeframe.

Contextual Audiences have two kinds of data collection periods:

  • static - a timeframe set between two dates in the last 180 days with a maximum 30 day period
  • dynamic - a rolling timeframe of up to the last 30 days from today with data refreshing every 24 hours

More resources:

Before You Begin​

To create a Contextual Audience, the following is required:

  1. An Account On the IQM platform
    • See Getting Started section to create an account and request a Client ID and Client Secret

Create a Contextual Audience Using the IQM API​

This Quickstart Guide will cover how to create a Contextual Audience using both keywords and URLs and each type of data collection period.

The minimum requirements to perform this task are: logging in with authentication credentials, creating an Audience, and checking the Audience status. Once these steps are accomplished, more can be learned about IQM's API through the Guidelines pages.

  1. Log In
    • Optional if you have already logged in and have a token
  2. Create a Contextual Audience
  3. Check the Audience Status

Step 1: Log in​

POST /api/v3/ua/login

To log in, the Authentication: Basic header is required. The Login API returns an OAuth-compliant response with an Organization Workspace ID (owId), a unique identifier for each Organization. This ID will be used for any further API communications.

For further information see the complete Login API Documentation.

Headers
Authentication
string required		Authentication bearer token
See Authentication Guide
X-IAA-HOST
string required		Workspace URL
Request Schema
grantType
string required		OAuth Grant Types
email
string required		User account email
password
string required		User account password
Request Schema
{
  "grantType": "password",
  "email": "pratik.t+ihp@iqm.com",
  "password": "123456"
}
Response 200
{
  "success": true,
  "data":
  {
    "access_token": "106adb25-37b0-4cab-8381-d682fe7cc3c8",
    "refresh_token": "eac4c1f6-781e-4b04-baff-9c2e415d1f64",
    "scope": "read write",
    "token_type": "bearer",
    "expires_in": 35999,
    "owId": 200001
  }
}
More Responses
Response 400
{
   "success": false,
   "data":
   {
      "status": "On Hold",
      "reason": "The particular account is kept on hold due to missed payment dates for last 3 months.",
      "supportEmail": "support@iqm.com"
   },
   "errorObjects":
   [
      {
         "error": "User is not allowed to access provided customer",
         "reason": "User is not associated with any active organization."
      }
   ]
}
Response 403
{
   "success": false,
   "errorObjects":
   [
      {
         "error": "User doesn't exist or user is not allowed to provided workspace."
      }
   ]
}

Step 2: Create a Contextual Audience​

POST /api/v3/audience/contextual/add

You can determine how a Contextual Audience forms groupings by indicating a list of relevant keywords and/or URLs. IQM adds users to the Contextual Audience when they visit a site relevant to those keywords or URLs.

The Request Schema table below details the supported fields for creating a Contextual Audience. Steps 2a and 2b detail two different ways to perform this action, however keywords and URLs can also be used together to create an Audience.

Request Schema
audienceName
string		Audience name
keywords
string		Keywords to generate contextual Audience
startDate
integer		Unix epoch start date, in milliseconds (required if data collection method is static)
endDate
integer		Unix epoch start date, in milliseconds (required if data collection method is static)
frequency
integer		The number of times a user visits the publisher(s) relevant to one or more keywords or URLs added to the contextual Audience. Integer between 1-10
urls
string		The publisher sites visited by a user
timezoneId
integer		Timezone ID specifies data collection start time
dataCollectionMethodId
integer		static (1) collection period in a fixed set of dates
dynamic (2) data collection period over a rolling timeframe, with data refreshes every 24 hours
dataCollectionDays
integer		Number of days for data collection timeframe when data collection method is dynamic (maximum value: 30)
Response Properties
id
integer		Audience ID
message
string		Success message

Step 2a: Contextual Audience with Keywords​

You can create a Contextual Audience with keywords and just a few other parameters. You will need to pass an audienceName and select one or more keywords. In the provided request sample (seen in the code block in the right-side column) the chosen keywords are "politics", "voters", and "california".

Next you will need to decide a frequency from 1-10. This determines how many times a user must visit a site relevant to the chosen keywords to be added to the Audience.

A Contextual Audience also requires specifying a timeframe for data collection. In this example you can choose a static data collection method by passing 1 as the dataCollectionMethodId. This method requires unix epoch values for the startDate and endDate fields.

info

The start date of a Contextual Audience must be within the last 180 days.

The period between the start date and the end date cannot exceed 30 days.

Lastly, a timezone ID is required to determine the data collection timeframe. An ID of 29 designates EST timezone.

Request Sample
{
  "audienceName": "California Politics",
  "frequency": 5,
  "keywords": "politics, voters, california",
  "dataCollectionMethodId": 1,
  "startDate": 1750737600000,
  "endDate": 1753329599000,
  "timezoneId": 29,
}
Response 200
{
  "success": true,
  "data": {
    "id": 1078146,
    "message": "Contextual Audience created successfully"
  }
}

Step 2b: Contextual Audience with URLs​

You can also create a Contextual Audience with URLs. You will need to pass the desired websites as a string in the urls field.

As in Step 2a, you will need to pass integers for frequency and timezoneId.

In this example you can choose a dynamic data collection method by passing 2 as the dataCollectionMethodId. This method requires passing a period of days (1-30) in the dataCollectionDays field.

Request Sample
{
  "audienceName": "California Politics",
  "frequency": 5,
  "urls": "www.iqm.com",
  "dataCollectionMethodId": 2,
  "dataCollectionDays": 20,
  "timezoneId": 29,
}
Response 200
{
  "success": true,
  "data": {
    "id": 1078146,
    "message": "Contextual Audience created successfully"
  }
}

Step 3: Check Audience Status​

GET /api/v3/audience/contextual/{audienceId}

You can check on the Audience status after creation to see if it's "Ready" or still "Processing". This endpoint will also return various details about the Audience as described in the Response Properties table below.

Use the id from Steps 2a or 2b and pass it as the audienceId in the endpoint path to get the Audience's details.

Path Parameter
audienceId
string		Audience ID
Response Properties
id
integer		Audience ID
name
string		Audience name
status
string		Audience status
type
integer		Audience Type ID
includedCount
integer		Count of Campaigns including this Audience
excludedCount
integer		Count of Campaigns excluding this Audience
createdOn
integer		Unix epoch creation date, in milliseconds
organizationName
string		Organization name
owId
integer		Organization Workspace ID
createdByUowId
integer		Created by User Organization Workspace ID
createdByUser
string		Created by user name
uniques
integer		Count of unique Audiences reached
dataCost
integer		Fees charged by the platform if the Audience is used in any Campaign
keywords
string		Keywords
urls
integer		URLs
startDate
integer		Unix epoch start date, in milliseconds
endDate
integer		Unix epoch end date, in milliseconds
frequency
integer		Frequency
editAccess
boolean		Indicates if user has edit access for the requested resource
Response 200
{
  "success": true,
  "data": {
    "id": 1078361,
    "name": "USA",
    "status": "Processing",
    "type": 5,
    "includedCount": 0,
    "excludedCount": 0,
    "createdOn": 1719382932,
    "organizationName": "IQM Corporation",
    "owId": 202314,
    "createdByUowId": 117790,
    "createdByUser": "Neeraj Khatri",
    "createdByUserEmail": null,
    "uniques": 0,
    "dataCost": 1.5,
    "keywords": "law,act,actions",
    "urls": "",
    "startDate": 1718873084000,
    "endDate": 1719229978000,
    "frequency": 2,
    "editAccess": true
  }
}